package com.currentcms.client.component.tree;


/**
 * Represents a tree to be used by the {@link TreeLayout}.
 * <p>
 * The TreeForTreeLayout interface is designed to best match the implemented
 * layout algorithm and to ensure the algorithm's time complexity promises in
 * all possible cases. However in most situation a client must not deal with all
 * details of this interface and can directly use the
 * {@link org.abego.treelayout.util.AbstractTreeForTreeLayout} to implement this
 * interface or even use the
 * {@link org.abego.treelayout.util.DefaultTreeForTreeLayout} class directly.
 * <p>
 * Also see <a href="package-summary.html">this overview</a>.
 * 
 * @author Udo Borkowski (ub@abego.org)
 * 
 * @param <TreeNode>
 */
public interface TreeForTreeLayout<TreeNode> {

	/**
	 * Returns the the root of the tree.
	 * <p>
	 * Time Complexity: O(1)
	 * 
	 * @return the root of the tree
	 */
	TreeNode getRoot();

	/**
	 * Tells if a node is a leaf in the tree.
	 * <p>
	 * Time Complexity: O(1)
	 * 
	 * @param node
	 * @return true iff node is a leaf in the tree, i.e. has no children.
	 */
	boolean isLeaf(TreeNode node);

	/**
	 * Tells if a node is a child of a given parentNode.
	 * <p>
	 * Time Complexity: O(1)
	 * 
	 * @param node
	 * @param parentNode
	 * @return true iff the node is a child of the given parentNode
	 */
	boolean isChildOfParent(TreeNode node, TreeNode parentNode);

	/**
	 * Returns the children of a parent node.
	 * <p>
	 * Time Complexity: O(1)
	 * 
	 * @param parentNode
	 *            [!isLeaf(parentNode)]
	 * @return the children of the given parentNode, from first to last
	 */
	Iterable<TreeNode> getChildren(TreeNode parentNode);

	/**
	 * Returns the children of a parent node, in reverse order.
	 * <p>
	 * Time Complexity: O(1)
	 * 
	 * @param parentNode
	 *            [!isLeaf(parentNode)]
	 * @return the children of given parentNode, from last to first
	 */
	Iterable<TreeNode> getChildrenReverse(TreeNode parentNode);

	/**
	 * Returns the first child of a parent node.
	 * <p>
	 * Time Complexity: O(1)
	 * 
	 * @param parentNode
	 *            [!isLeaf(parentNode)]
	 * @return the first child of the parentNode
	 */
	TreeNode getFirstChild(TreeNode parentNode);

	/**
	 * Returns the last child of a parent node.
	 * <p>
	 * 
	 * Time Complexity: O(1)
	 * 
	 * @param parentNode
	 *            [!isLeaf(parentNode)]
	 * @return the last child of the parentNode
	 */
	TreeNode getLastChild(TreeNode parentNode);
}